home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER09.TXT < prev    next >
Text File  |  1995-05-29  |  14KB  |  330 lines
  1.                                 Prompt Dialogs
  2.  
  3.                            "All is not gold that outward sheweth bright"
  4.                                                             Lydgate
  5.  
  6. Introduction
  7.  
  8.           In Chapter 4 you learned about the message functions such as
  9.      PromptOK and PromptYesNo. These functions make it easy to display a
  10.      message and prompt the user to select a button. The GOLDREAD unit
  11.      takes the feature one step further and allows the user to input
  12.      data such as strings, integers and even select a radio button. If
  13.      you want to prompt the user to input a single standard field type,
  14.      you don't need to build a custom IO form, just use GOLDREAD's
  15.      prompt functions.
  16.  
  17.      Figure 9.1 shows the PromptStr function in action.
  18.  
  19.  
  20.      Figure 9.1
  21.      The PromptStr
  22.      dialog
  23.  
  24.  
  25. A Prompt Function Summary
  26.  
  27.           List below is a summary of the prompt functions supplied in
  28.      the GOLDREAD unit:
  29.  
  30.      PromptStr(X,Y,StrFldLen:byte;Lab,Tit:StrScreen; Default:string;
  31.                                               Caps:boolean): string;
  32.  
  33.           Prompts the user to enter a string. If the field length is too
  34.      long for the dialog, Gold will automatically use a scrollable
  35.      string field. PromptStr will optionally convert all input to
  36.      uppercase.
  37.  
  38.      PromptNum(X,Y:byte;Lab,Tit:StrScreen;Default,Min,Max:LongInt;
  39.                                              Spin:boolean): longint;
  40.  
  41.           Prompts the user to input a whole number within the specified
  42.      range. The field optionally displays spinners to allow the user to
  43.      scroll through a range of numbers.
  44.  
  45.      PromptReal(X,Y:byte;Lab,Tit:StrScreen;Fmat:string;Default,
  46.                                             Min,Max:extended): extended;
  47.  
  48.           Prompts the user to input a real number within the specified
  49.      range. The field optionally displays spinners to allow the user to
  50.      scroll through a range of numbers.
  51.  
  52.      PromptFixedReal(X,Y:byte;Lab,Tit:StrScreen;WLen,DP:byte;Default,
  53.                          Min,Max,Delta:extended;Spin:boolean): extended;
  54.  
  55.           Like FixedReal except the field has a fixed decimal place.
  56.  
  57.      PromptDate(X,Y:byte;Lab,Tit:StrScreen;Fmat:gDate;Default,
  58.                                 Min,Max:Dates;Spin,Drop:boolean): Dates;
  59.  
  60.           Prompts the user to enter a date within the specified range.
  61.      All the Gold date formats are supported. The field optionally
  62.      displays spinners to allow the user to scroll through a range of
  63.      numbers, as well as an optional drop down calendar.
  64.  
  65.      PromptRadio(X,Y:byte;Lab,Tit:StrScreen;Fields:string;
  66.                                                  Default:byte): byte;
  67.  
  68.           Prompts the user to select an item from a list of up to 13
  69.      radio button items. The radio button text for all the items is
  70.      defined in a single string, with each option delimited by the '|'
  71.      character.
  72.  
  73.      PromptColor(X,Y,Default:byte;Cmt,Tit:StrScreen): byte;
  74.  
  75.           Prompts the user to select a display attribute, i.e.
  76.      background and foreground colors. This dialog is highly
  77.      customizable. Refer to the section Prompting for Colors for more
  78.      information.
  79.  
  80.           The user can optionally escape from these dialogs. If you need
  81.      to know whether the user escaped, check the value of the variable
  82.      ReadVars.LastAction, which will be set to Escaped if the user
  83.      selects the Cancel button, or clicks on the close icon.
  84.  
  85.      Here are a few tips to help you customize the dialog's appearance:
  86.  
  87.           Window Position - Each function accepts X and Y parameters
  88.                which identify the upper left coordinates of the dialog
  89.                window. If X is specified as zero, the dialog will be
  90.                horizontally centered. Similarly, if Y is specified as
  91.                zero, the dialog will be vertically centered. You guessed
  92.                it, if both X and Y are set to zero, the dialog will be
  93.                automatically positioned in the middle of the display.
  94.  
  95.           Window Style - You can customize the prompt window style by
  96.                assigning a value in the range 1 to 9 to the variable
  97.                ReadVars.PromptStyle. At program start-up the default
  98.                window style is set to the same style as PromptOK, i.e.
  99.                the style specified in WinVars.PromptStyle.
  100.  
  101.           Label Position - By default, the optional field label is
  102.                positioned to the left of the field (except for
  103.                PromptRadio). To position the label above the field,
  104.                simply start the label with the '^' character, e.g.
  105.                '^Enter your name'.
  106.  
  107.           Number Ranges - The number and prompt related prompts require
  108.                that you specify a maximum and minimum acceptable value.
  109.                If you want the user to be able to enter any value (i.e.
  110.                disable the range limits), specify the min and max values
  111.                as zero.
  112.  
  113.           Controlling Gaps - The gaps or whitespace to the left and
  114.                right of the dialog, i.e. the area between the input
  115.                field and the window border, is controlled by the
  116.                variable ReadVars.OutsideGap. The default value is 2. The
  117.                gap between the buttons is similarly controlled by the
  118.                variable ReadVars.ButtonGap, which also has a default of
  119.                2 characters.
  120.  
  121.  
  122.           Run the demo files DEMRD1.PAS through DEMRD7.PAS to see the
  123.      prompt functions in action.
  124.  
  125. Prompting for Passwords
  126.  
  127.           In some instances, you may not want the user's input to be
  128.      echoed to the screen. For example, you may be prompting the user to
  129.      enter a password.
  130.  
  131.           You can force the PromptStr function to echo an asterisk to
  132.      the screen whenever a character is typed by setting the boolean
  133.      variable ReadVars.Password to TRUE.
  134.  
  135.  
  136.      The demo program DEMRD9.PAS illustrates this technique.
  137.  
  138. Prompting for Colors
  139.  
  140.           The PromptColor function is designed for applications that
  141.      allow the end users to select their own display colors. It displays
  142.      two lists of colors; one for the foreground and one for the
  143.      background. A visual sample of the active selection is displayed.
  144.  
  145.           You can assign a function to display a custom visual sample by
  146.      calling the function AssignTextSampleHook. By default, the dialog
  147.      only allows two or three lines in which to display the sample. If
  148.      you want more space to display the sample, change the value of the
  149.      variable ReadVars.ColorWinDepth to reflect the total number of
  150.      lines required in the window.
  151.  
  152.           The sample hook must be declared as a far procedure at the
  153.      root level, and must be passed two byte parameters -- the second
  154.      parameter being a variable. The first parameter identifies the
  155.      active field, and the second parameter is a refresh code which
  156.      informs Gold about which fields need to be redrawn -- either set
  157.      the second parameter to RefreshNone or RefreshAll. These constants
  158.      are declared in the GOLDIO unit.
  159.  
  160.           From within the hooked procedure you can ascertain the current
  161.      values for the foreground and background by inspecting the
  162.      variables ReadVars.ForegroundByte and ReadVars.BackgroundByte.
  163.  
  164.           Listed below is an extract of the demo file DEMRD8.PAS which
  165.      customizes the color hook:
  166.  
  167.  
  168.           {$F+}
  169.           procedure NewTextHook(CurrentField:byte;var Refresh:byte);
  170.           {}
  171.           var A: byte;
  172.           begin
  173.              with ReadVars do
  174.              begin
  175.                 A := Cattr(pred(ForeGroundByte),
  176.                             pred(BackGroundByte));
  177.                 Refresh := RefreshOthers;
  178.                 case CurrentField of
  179.                    0,1,2,3: ;
  180.                    3: CheckBrightFlags(A);
  181.                    else Refresh := RefreshNone;
  182.                 end;
  183.                 if Refresh = RefreshOthers then
  184.                 begin
  185.                    Box3D(2,10,46+
  186.                          2*Ord(not PromptStyle in [7,8]),18,
  187.                          BlackOnCyan,WhiteOnCyan,8);
  188.                    PartClear(5,11,43+2*Ord(not
  189.                              PromptStyle in [7,8]),17,A,' ');
  190.                    WriteAT(5,11,A,'Help on the Colors dialog');
  191.                    WriteAT(5,13,A,'GOLD includes SampleHook...');
  192.                    WriteAT(5,14,A,'permits the developer ...');
  193.                    WriteAT(5,15,A,'to the PromptColor ....');
  194.                 end;
  195.              end;
  196.           end; { NewTextHook }
  197.           {$F-}
  198.  
  199.           begin
  200.              with ReadVars do
  201.              begin
  202.                 ColorWinDepth := 19;
  203.                 PromptStyle := 4;
  204.                 BlinkingOn := false;
  205.              end;
  206.              UseCustomChars;
  207.              MouseShow(true);
  208.              AssignTextSampleHook(NewTextHook);
  209.              TmpColor := PromptColor(0,4,RedOnCyan,'Pick color',
  210.                                      'GoldRead Color Input');
  211.              .....
  212.           end.
  213.  
  214.           By default, the PromptColor background color list only
  215.      includes the first 8 colors, i.e. the bright colors are excluded.
  216.      Set the boolean variable ReadVars.Use16BgndColors variable to true
  217.      to instruct Gold to support all 16 colors for the background field.
  218.  
  219. Adding a Help Routine
  220.  
  221.           By default, the prompt dialogs do not include a help button.
  222.      However, a help button will automatically appear when you use the
  223.      following procedure:
  224.  
  225.      AssignReadHelpHook(PFHook: PromptHelpHook);
  226.  
  227.           Assigns a help procedure to the Prompt dialogs in GOLDREAD.
  228.      The passed procedure must be declared far and have no passed
  229.      parameters.
  230.  
  231.           The hooked procedure will be called whenever the user selects
  232.      the Help button. To subsequently remove the Help button, call the
  233.      procedure RemoveReadHelpHook before displaying the dialog.
  234.  
  235.      Run DEMRD10.PAS for a demonstration of the custom help facility.
  236.  
  237. Customizing the Dialog Colors
  238.  
  239.           To customize the display colors of the prompt dialogs, use the
  240.      GoldSetColor function to set one of the following color components:
  241.  
  242.           PromptBorder1
  243.           PromptBorder2
  244.           PromptTitle
  245.           PromptBody
  246.           PromptButtonHiHot
  247.           PromptButtonHi
  248.           PromptButtonNormHot
  249.           PromptButtonNorm
  250.           PromptButtonDefHot
  251.           PromptButtonDef
  252.           PromptIcons
  253.           PromptBodyHi
  254.           PromptNormalCmt
  255.           PromptHiCmt
  256.           PromptEditErase
  257.           PromptEditNorm
  258.           PromptEditHi
  259.  
  260.           Listed below is an extract from DEMRD11.PAS which updates all
  261.      the prompt colors:
  262.  
  263.           procedure CustomizeColors;
  264.           {}
  265.           begin
  266.              GoldSetColor(PromptBorder1,LightRedOnRed);
  267.              GoldSetColor(PromptBorder2,LightRedOnRed);
  268.              GoldSetColor(PromptTitle,WhiteOnRed);
  269.              GoldSetColor(PromptBody,LightGrayOnRed);
  270.              GoldSetColor(PromptButtonHiHot,WhiteOnMagenta);
  271.              GoldSetColor(PromptButtonHi,YellowOnMagenta);
  272.              GoldSetColor(PromptButtonNormHot,YellowOnMagenta);
  273.              GoldSetColor(PromptButtonNorm,LightgrayOnMagenta);
  274.              GoldSetColor(PromptButtonDef,LightgrayOnMagenta);
  275.              GoldSetColor(PromptButtonDefHot,LightcyanOnMagenta);
  276.              GoldSetColor(PromptIcons,LightcyanOnRed);
  277.              GoldSetColor(PromptBodyHi,WhiteOnRed);
  278.              GoldSetColor(PromptNormalCmt,YellowOnRed);
  279.              GoldSetColor(PromptHiCmt,WhiteOnRed);
  280.              GoldSetColor(PromptEditErase,WhiteOnGreen);
  281.              GoldSetColor(PromptEditNorm,LightGrayOnMagenta);
  282.              GoldSetColor(PromptEditHi,WhiteOnMagenta);
  283.           end; { CustomizeColors }
  284.  
  285. Customizing the Button Text and Error Messages
  286.  
  287.           International developers (and developers in Louisiana) may
  288.      want to translate the strings used in the prompt dialogs.
  289.  
  290.           The button text along with the button hotkeys use the common
  291.      buttons declared in GOLDWIN. You can modify the default buttons by
  292.      changing the values of the following WinVars variables (shown with
  293.      their default assignments):
  294.  
  295.              with WinVars do
  296.              begin
  297.                 OKButStr := '   ~O~K   ';
  298.                 OKHotKey := 280;          { Alt+O }
  299.                 CancelButStr := ' ~C~ancel ';
  300.                 CancelHotKey := 302;      { Alt+C }
  301.                 HelpButStr := '  ~H~elp  ';
  302.                 HelpHotKey := 291;
  303.              end;
  304.  
  305.           The PromptColor function uses an additional set of strings,
  306.      which are all defined in the ReadVars record. Listed below are the
  307.      string variables in ReadVars along with their default values:
  308.  
  309.           BrightLabel := 'B~r~ight background';
  310.           FGLabel := '~F~oreground';
  311.           BGLabel := '~B~ackground';
  312.           FGHotKey := 289;          { Alt+F }
  313.           BGHotKey := 304;          { Alt+B }
  314.           BrightLabelHotKey := 275; { Alt+R }
  315.           SampleText := ' Text Text Text ';
  316.           SampleTxtHdr := 'Sample Text';
  317.           LowerSet := 'Black|Blue|Green|Cyan|Red|
  318.                        Magenta|Brown|LightGray';
  319.           UpperSet := 'DarkGray|LightBlue|LightGreen|LightCyan|
  320.                        LightRed|LightMagenta|Yellow|White';
  321.  
  322. Error Handling
  323.  
  324.           All the prompt functions discussed in this chapter have the
  325.      potential to fail. The most probable cause of error is a lack of
  326.      memory to construct the window. After calling one of the functions,
  327.      always call the function LastReadError to see whether the operation
  328.      was successful.
  329.  
  330.